home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 001 / jmodem.arc / JMODEM.DOC < prev    next >
Text File  |  1988-09-13  |  13KB  |  316 lines
  1.  
  2.                                   J M O D E M
  3.                               File Transfer System
  4.                                  Compliments of
  5.                                Richard B. Johnson
  6.                                 PROGRAM EXCHANGE
  7.                                  (719) 548-0108
  8.                                September 13, 1988
  9.  
  10.           General:
  11.           First Let me get this over with.
  12.           MS-DOS is a registered trademark of Microsoft Corporation
  13.           IBM, IBM-PC, IBM-XT, AT, are registered trademarks of Inter-
  14.           national Business Machines, Inc. WILDCAT! is a trademark of
  15.           Mustang Software. XMODEM is a public-domain file-transfer
  16.           protocol developed by Ward Christensen.
  17.  
  18.           JMODEM is released into the public domain. As with most
  19.           public-domain protocols, you are advised that there is no
  20.           implied warranty of any kind. The source-code is provided so
  21.           that you may determine for yourself if this program may
  22.           serve a useful purpose. It is written in Microsoft MASM
  23.           Assembly-language using good standards of engineering prac-
  24.           tice. It does not use any strange or "undocumented" func-
  25.           tions of the MS-DOS operating system.
  26.  
  27.                 PLEASE UPLOAD THIS FILE (The ARC file) to as many
  28.                 BBS systems as you can so that it gets installed
  29.                 all around the country.
  30.  
  31.           Introduction:
  32.           JMODEM is a new file-transfer protocol developed to be used
  33.           as an "external protocol" on BBS systems and personal com-
  34.           puters using the IBM-PC/AT/XT structure and the MS-DOS oper-
  35.           ating system.
  36.  
  37.           This file-transfer system features:
  38.  
  39.                 o       16-bit CRC for verification
  40.                 o       File size is exactly maintained
  41.                 o       Data compression.
  42.                 o       Rapid host/remote synchronization.
  43.                 o       Variable-length transmission blocks which,
  44.                         if there are few errors, increase to 8192
  45.                         data-bytes in length.
  46.                 o       Flow control (automatic)
  47.                 o       Hangup protection
  48.                 o       Aborted files are saved
  49.                 o       Files being overwritten are renamed to
  50.                         ".OLD", rather than deleted.
  51.                 o       COM1 / COM2 support.
  52.                 o       Interrupt on received characters allows data
  53.                         to be received while the previous block is
  54.                         being written to disk. This provides almost
  55.                         continuous data transmission without long
  56.                         waits between blocks.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                      - 1 -
  63.           
  64.  
  65.           JMODEM is not for everyone! It does not have any pretty
  66.           screens to dazzle the user. It is designed to maximize the
  67.           amount of data that can be transferred in a given time (and
  68.           reduce telephone cost). It does this by sending very long
  69.           blocks of data and encoding (compressing) the data wherever
  70.           possible. Since long blocks of data are subject to many
  71.           transmission errors, a 16 bit CRC is used to determine the
  72.           data integrity. As many as ten retries are made if the data
  73.           is not correctly received. If you have a noisy telephone
  74.           circuit, you will find that JMODEM will abort more often
  75.           than the XMODEM protocol which sends very short blocks. A
  76.           future version that will be downward-compatible with the ex-
  77.           isting version is being developed that will do "heroic"
  78.           retries and will even go down to a 16-byte block-lengths if
  79.           that's what is necessary to get the data transferred.
  80.  
  81.           Once synchronization between the remote computer and the
  82.           host are established, JMODEM paints a status block on the
  83.           screen that shows how the file transfer is going. The status
  84.           screen shows the block being transmitted (or the last
  85.           received), the length of the block, and the total bytes hav-
  86.           ing been transmitted (or received). A special synch-
  87.           ronization routine is used so that the first block is not
  88.           thrown away as happens so often in XMODEM type routines.
  89.           During the synchronization routine, where the host is wait-
  90.           ing for the user to enter the proper file parameters (a 30
  91.           second wait).  You can abort immediately by sending a con-
  92.           trol X (^X). After actual file transfer begins, ie. when you
  93.           see the status window on the screen, no input from the key-
  94.           board is possible. You send a control BREAK to abort the
  95.           transmission (or ^C). In this case, the program will abort
  96.           after the block being sent/received is complete. This could
  97.           take 15 or more seconds with long blocks so be patient.
  98.  
  99.           In the event that carrier is lost (the user disconnected),
  100.           the file-transfer program will also abort. This, too, could
  101.           take as long as 15 seconds.
  102.  
  103.           How it works:
  104.           The block size starts out at 512 bytes (or the actual bytes
  105.           in the file -- whichever is less). To this is added a 6-byte
  106.           overhead. If the block transfer occurred without any
  107.           retries, the block length is increased by 512 bytes to 1024
  108.           bytes. As long as the transmission was successful without
  109.           incurring any re-tries, the block-length increases to a max-
  110.           imum of 8192 bytes. There is still the same 6-byte overhead
  111.           so the maximum block length will actually be 8198 bytes. Any
  112.           time there are retries, the block length (on the next new
  113.           string) is decreased by 512 bytes. The string-length is
  114.           never reduced to less than 512 bytes due to errors. When the
  115.           last bytes are read from the file, the block length may be
  116.           as little as 7 bytes (one data byte, plus the 6 byte over-
  117.           head). The file size as received will be exactly the file
  118.           size as transmitted. XMODEM will "round-up" the file size to
  119.           the next higher block. This means that MS-DOS's COMP (com-
  120.  
  121.  
  122.  
  123.  
  124.  
  125.                                      - 2 -
  126.           
  127.           pare) will always fail when you attempt to check files that
  128.           have been sent by XMODEM and many other protocols.
  129.  
  130.           When the file is read, an attempt is made to compress the
  131.           data using the well-known RLL process where multiple bytes
  132.           are compressed into a 4-byte statement.
  133.  
  134.           For instance a string that looks like this (hex):
  135.                 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
  136.           Gets compressed into this:
  137.                 BB 0F 00 A0
  138.                  |  |  |  |__________ Byte to repeat
  139.                  |  |  |_____________ High byte of repeat length
  140.                  |  |________________ Low byte of repeat length
  141.                  |___________________ Sentinel Byte
  142.  
  143.           The sentinel-byte (BBH), when encountered in a data stream
  144.           will get expanded to four bytes. Therefore, it is possible
  145.           for the "compressed" data string to actually be longer than
  146.           the original. If this occurs, the original string is sent
  147.           rather than the longer encoded one. Since the kind of data
  148.           sent can be different from block-to-block, it is necessary
  149.           to send a control-byte along with the data so the receiver
  150.           had determine how to operate on the data.
  151.  
  152.           This is the control structure:
  153.  
  154.           00 02 00 0B 01 02 03 04 05 06 07 08 09 0A .... 0A EA
  155.            |  |  |  |  |                                 |  |_ CRC
  156.            |  |  |  |  |                                 |____ CRC
  157.            |  |  |  |  |______________________________________ data
  158.            |  |  |  |_________________________________________ rec.
  159.            |  |  |____________________________________________ control
  160.            |  |_______________________________________________ length
  161.            |__________________________________________________ Length
  162.  
  163.           Two bytes are used for the string length and two bytes are
  164.           used for the CRC. As is standard in memory, the high-byte
  165.           looks "to people using DEBUG" swapped with the low byte. The
  166.           data is transmitted exactly as the memory image.
  167.  
  168.           The length (a word) begins the string so the receiver may
  169.           know exactly how may bytes to receive.
  170.  
  171.           The control byte is bit-mapped to 8 possibilities. The ones
  172.           most important are:
  173.  
  174.                         NORMAL DATA
  175.                         COMPRESSED DATA
  176.                         END OF FILE
  177.                         ABORT
  178.  
  179.           This is now the receiver "knows" what to do with the data.
  180.  
  181.           The CRC is generated using this polynomial:
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.                                      - 3 -
  189.           
  190.           X =  X + X^(2(n-mod 7).......  Where n = t(n-1)
  191.                                          And t = string length
  192.  
  193.           It has the advantage of simplicity in assembly-language pro-
  194.           gramming and will detect errors with a probability of about
  195.           one undetected error in 2^132 (which is a very large num-
  196.           ber). It does not correct errors so its not important to use
  197.           some "standard" function to generate the CRC.
  198.  
  199.           Usage:
  200.           This program uses parameters on the command line.
  201.  
  202.           JMODEM S <filename.typ>       ( Sends a file to COM1:)
  203.           JMODEM R <filename.typ>       ( Receives a file from COM1:)
  204.           JMODEM S1 <filename.typ>      ( Sends a file to COM1:)
  205.           JMODEM R1 <filename.typ>      ( Receives a file from COM1:)
  206.           JMODEM S2 <filename.typ>      ( Sends a file to COM2:)
  207.           JMODEM R2 <filename.typ>      ( Receives a file from COM2:)
  208.  
  209.           Support for COM3 and COM4 have been added on revision level
  210.           V1.05 . Note that the standards for port locations are de-
  211.           facto standards only and may not be the ports actually used
  212.           in your computer. Please modify the communications port
  213.           structures at the beginning of the assembly-language program
  214.           to match your system parameters if they are different. The
  215.           modifications should be done to the STRUCTURES, not to the
  216.           EQUATES!
  217.  
  218.  
  219.           In a batch file, <filename.typ> may be a substitution
  220.           character.
  221.           JMODEM S2 %1                  ( Sends a file to COM2:)
  222.           JMODEM R2 %1                  ( Receives a file from COM2:)
  223.  
  224.           How to set up batch files to use this program:
  225.           If you are using PCPLUS (PROCOMM +), the batch files should
  226.           be set up like this:
  227.  
  228.           (JDOWN.BAT)
  229.           JMODEM R1 %1                  ( Download from COM1:)
  230.  
  231.           (JUP.BAT)
  232.           JMODEM S1 %1                  ( Upload to COM1:)
  233.  
  234.           If you are running a WILDCAT! bulletin board, the external
  235.           protocol files should be set up like this:
  236.  
  237.           (JUP.BAT)
  238.           CD D:\WILDCAT\PROTOCOL
  239.           IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  240.           JMODEM R1 %3
  241.           IF ERRORLEVEL 1 GOTO END
  242.           COPY %3 %4
  243.           :END
  244.           DEL %3
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.                                      - 4 -
  252.           
  253.           (JDOWN.BAT)
  254.           CD D:\WILDCAT\PROTOCOL
  255.           IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  256.           JMODEM S1 %3
  257.           IF ERRORLEVEL 1 GOTO BAD
  258.           GOTO END
  259.           :BAD
  260.           COPY ALL.OK TRANSFER.BAD
  261.           :END
  262.  
  263.           JMODEM does not require any information about handshaking.
  264.           It will look at the modem port and figure out for itself
  265.           what to do.
  266.  
  267.           In the event that the modem carrier is lost, JMODEM will
  268.           abort. Since JMODEM only checks the modem port occasionally,
  269.           it may take several seconds to abort when the carrier is
  270.           lost. It is impossible for a user to get at the DOS level
  271.           through JMODEM. Do NOT use the CTTY command in the external
  272.           protocol batch files. JMODEM returns ERRORLEVEL 1 if there
  273.           was any error in transmission or reception. It returns ER-
  274.           RORLEVEL 0 (no error) otherwise. It does not delete files
  275.           that have been partially received although it properly
  276.           closes them. The system operator can arrange the batch files
  277.           to delete them if required.
  278.  
  279.           When JMODEM attempts to create a file that already exists it
  280.           can't ask the user if the old one should be deleted since
  281.           the user is probably not in a terminal program at the time.
  282.           Therefore, JMODEM renames the other file to <filename.OLD>
  283.           and creates the new file.
  284.  
  285.           - Finis -
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.                                      - 5 -
  315.           
  316.